The
Form plugin is a terrific example of a script that makes a difficult,
complex task dead simple. The plugin file, along with detailed
documentation, is available at http://malsup/com/jquery/form/.
At the heart of the plugin is the .ajaxForm() method. Converting a conventional form into an AJAX form requires one simple line of code:
$(document).ready(function() {
$('#myForm').ajaxForm();
});
This example will prepare<form id="myForm">
to be submitted without having to refresh the current page. This
feature in itself is quite nice, but the real power comes with the map
of options that we can pass into the method. For example, the following
code calls .ajaxForm() with the target, beforeSubmit, and success options:
$(document).ready(function() {
function validateForm() {
// the form validation code would go here
// we can return false to abort the submit
};
$('#test-form').ajaxForm({
target: '#log',
beforeSubmit: validateForm,
success: function() {
alert('Thanks for your comment!');
}
});
});
The target option indicates the element(s)—in this case, an element with id="log"—that will be updated by the server response.
The beforeSubmit option performs tasks before the form is submitted. Here, it references the validateForm() function. If the function returns false, the form will not be submitted.
The success
option performs tasks after the form is successfully submitted. In this
example it simply provides an alert message to let the user know that
the form has been submitted.
Other options available with .ajaxForm() and the similar .ajaxSubmit() include:
url: The URL to which the form data will be submitted, if different from the form's action attribute.
type: The method used to submit the form—either GET or POST. The default is the form's method attribute, or if none is provided, GET.
dataType: The expected data-type of the server response. Possible values are null, xml, script, or json. The default value is null (an HTML response).
resetForm:
Boolean; default is false. If set to true, all of the form's field values will be reset to their defaults when the submit is successful.
clearForm:
Boolean; default is false. If set to true, all of the form's field values will be cleared when the submit is successful.
The Form plugin provides a
number of other methods to assist in handling forms and their data. For
a closer look at these methods, as well as more demos and examples,
visit http://www.malsup.com/jquery/form/.
Tips and tricks
The .ajaxForm() method is usually more convenient than the .ajaxSubmit()
method, at the expense of a little flexibility. When we want the plugin
to manage all the event binding for us, as well as invoke the .ajaxSubmit() method for us at the appropriate time, we should use .ajaxForm(). When we want finer-grained control over the submit event handling, .ajaxSubmit() is recommended.
Both .ajaxForm() and .ajaxSubmit() default to using the action and method
values in the form's markup. As long as we use proper markup for the
form, the plugin will work exactly as we expect without any need for
tweaking. As an additional benefit, we automatically gain the
advantages of progressive enhancement; the form is fully functional without JavaScript enabled.
Normally when a form is submitted, if the element used to submit the form has a name, its name and value attributes are submitted along with the rest of the form data. The .ajaxForm() method is proactive in this regard, adding click handlers to all of the<input type="submit"> elements so it knows which one submitted the form. The method, on the other hand, is reactive and has no way of determining this information. It does not capture the submitting element. The same distinction applies to<input type="image"> elements as well: .ajaxForm() handles them, while .ajaxSubmit() ignores them. .ajaxSubmit()
Unless a file is being uploaded as part of the form submission, the .ajaxForm() and .ajaxSubmit() methods pass their options argument to the $.ajax() method that is part of the jQuery core. Therefore, any valid options for $.ajax()
can be passed in through the Form plugin. With this feature in mind, we
can make our AJAX form responses even more robust, like so:
$(document).ready(function() {
$(#myForm).ajaxForm({
timeout: 2000,
error: function (xml, status, e) {
alert(e.message);
}
});
});
When less customization is required, the .ajaxForm() and .ajaxSubmit()
methods can be passed a function instead of an options map. Since the
function is treated as the success handler, we can get the response
text back from the server, like so:
$(document).ready(function() {
$(#myForm).ajaxForm(function(responseText) {
alert(responseText);
});
});
